﻿<!DOCTYPE HTML>
<html lang="zh">
<head>
<title>FileSelect - 语法 &amp; 使用 | AutoHotkey v2</title>
<meta name="description" content="The FileSelect function displays a standard dialog that allows the user to open or save file(s)." />
<meta name="ahk:equiv-v1" content="commands/FileSelectFile.htm" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<script type="text/javascript">$(function(){0<=window.navigator.userAgent.toLowerCase().indexOf("ucbrowser")&&CaoNiMaDeUc()})</script>
</head>
<body>

<h1>FileSelect</h1>

<p>Displays a standard dialog  that allows the user to open or save file(s).</p>

<pre class="Syntax">SelectedFile := <span class="func">FileSelect</span>(<span class="optional">Options, RootDir\Filename, Prompt, Filter</span>)</pre>
<h2 id="Parameters">参数</h2>
<dl>

  <dt>Options</dt>
  <dd>
      <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
      <p>If omitted, it will default to zero, which is the same as having none of the options below.</p>
      <p><strong>M</strong>: Multi-select. Specify the letter M to allow the user to select more than one file via shift-click, control-click, or other means. <strong>M</strong> may optionally be followed by a number as described below (例如, both M and M1 are valid). To extract the individual files, 请参阅 the example at the bottom of this page.</p>
      <p><strong>S</strong>: Save button. Specify the letter S to cause the dialog to always contain a Save button instead of an Open button. <strong>S</strong> may optionally be followed by a number (or sum of numbers) as described below (例如, both S and S24 are valid).</p>
      <p>Even if <strong>M</strong> and <strong>S</strong> are absent, the following numbers can be used. To put more than one of them into effect, add them up. 例如, to use 8 and 16, specify the number 24.</p>
      <p><strong>1</strong>: File Must Exist<br>
        <strong>2</strong>: Path Must Exist<br>
        <strong>8</strong>: Prompt to Create New File<br>
        <strong>16</strong>: Prompt to Overwrite File<br>
        <strong>32</strong>: Shortcuts (.lnk files) are selected as-is rather than being resolved to their targets. This option also prevents navigation into a folder via a folder shortcut.</p>
      <p>If the &quot;Prompt to Overwrite&quot; option is present without the &quot;Prompt to Create&quot; option, the dialog will contain a Save button rather than an Open button. This behavior is due to a quirk in Windows.</p>
  </dd>

  <dt>RootDir\Filename</dt>
  <dd>
      <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
      <p>If present, this parameter contains one or both of the following:</p>
      <p><strong>RootDir</strong>: The root (starting) directory, which is assumed to be a subfolder in <a href="../Variables.htm#WorkingDir">A_WorkingDir</a> if an absolute path is not specified. If omitted or blank, the starting directory will be a default that might depend on the OS version (it will likely be the directory most recently selected by the user during a prior use of FileSelect).</p>
      <p><strong>Filename</strong>: The default filename to initially show in the dialog's edit field. Only the naked filename (with no path) will be shown. To ensure that the dialog is properly shown, ensure that no illegal characters are present (such as /&lt;|:&quot;).</p>
      <p>Examples:</p>
      <pre>"C:\My Pictures\Default Image Name.gif"  <em>; Both <i>RootDir</i> and <i>Filename</i> are present.</em>
"C:\My Pictures"  <em>; Only <i>RootDir</i> is present.</em>
"My Pictures"  <em>; Only <i>RootDir</i> is present, and it's relative to the current working directory.</em>
"My File"  <em>; Only <i>Filename</i> is present (but if &quot;My File&quot; exists as a folder, it is assumed to be <i>RootDir</i>).</em></pre>
  </dd>

  <dt>Prompt</dt>
  <dd>
      <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
      <p>Text displayed in the window to instruct the user what to do. If omitted or blank, it will default to <code>"Select File - " <a href="../Variables.htm#ScriptName">A_ScriptName</a></code> (i.e. the name of the current script).</p>
  </dd>

  <dt>Filter</dt>
  <dd>
      <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
      <p>Indicates which types of files are shown by the dialog.</p>
      <p>Example: Documents (*.txt)<br>
        Example: Audio (*.wav; *.mp2; *.mp3)</p>
      <p>If omitted, the filter defaults to All Files (*.*). An option for Text Documents (*.txt) will also be available in the dialog's &quot;files of type&quot; menu.</p>
    <p>Otherwise, the filter uses the indicated string but also provides an option for All Files (*.*) in the dialog's &quot;files of type&quot; drop-down list. To include more than one file extension in the filter, separate them with semicolons as illustrated in the example above.</p>
  </dd>

</dl>

<h2 id="Return_Value">返回值</h2>
<p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
<p>If multi-select is not in effect, this function returns the full path and name of the single file chosen by the user.</p>
<p>If the M option (multi-select) is in effect, this function returns a list of items, each of which except the last is followed by a linefeed (`n) character. The first item in the list is the path that contains all the selected files (this path will end in a backslash only if it is a root folder such as C:\). The other items are the selected filenames (without path). 例如:</p>
<pre>C:\My Documents\New Folder [this is the path in which all the files below reside]
test1.txt [these are the naked filenames: no path info]
test2.txt
... etc.</pre>
<p>(The example at the bottom of this page demonstrates how to extract the files one by one.)</p>
<p>When multi-select is in effect, the sum of the lengths of the selected filenames is limited to 64 KB. Although this is typically enough to hold several thousand files, an empty string is returned if the limit is exceeded.</p>
<p>In both cases, if the user cancels the dialog (i.e. does not wish to select a file), an empty string is returned.</p>

<h2>ErrorLevel</h2>
<p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 1 if the user dismissed the dialog without selecting a file (such as by pressing the Cancel button). It is also set to 1 if the system refused to show the dialog (rare). Otherwise, it is set to 0.</p>
<h2 id="Remarks">备注</h2>
<p>A file-selection dialog usually looks like this:</p>
<img src="../static/dlg_file.png" alt="FileSelect" />
<p>A GUI window may display a modal file-selection dialog by means of the <a href="../objects/Gui.htm#OwnDialogs">+OwnDialogs</a> option. A modal dialog prevents the user from interacting with the GUI window until the dialog is dismissed.</p>
<p>Known limitation: A <a href="SetTimer.htm">timer</a> that launches during the display of a FileSelect dialog will postpone the effect of the user's clicks inside the dialog until after the timer finishes. To work around this, avoid using timers whose subroutines take a long time to finish, or disable all timers during the dialog:</p>
<pre><a href="Thread.htm">Thread</a> "NoTimers"
SelectedFile := FileSelect()
Thread "NoTimers", false</pre>

<h2 id="Related">相关</h2>
<p><a href="DirSelect.htm">DirSelect</a>, <a href="MsgBox.htm">MsgBox</a>, <a href="InputBox.htm">InputBox</a>, <a href="ToolTip.htm">ToolTip</a>, <a href="../objects/Gui.htm">GUI</a>, <a href="../misc/CLSID-List.htm">CLSID List</a>, <a href="LoopParse.htm">parsing loop</a>, <a href="SplitPath.htm">SplitPath</a></p>
<p>Also, the operating system offers standard dialog boxes that prompt the user to pick a font, color, or icon. These dialogs can be displayed via <a href="DllCall.htm">DllCall</a> as demonstrated at <a href="https://github.com/majkinetor/mm-autohotkey/tree/master/Dlg">GitHub</a>.</p>
<h2 id="Examples">示例</h2>
<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a></p>
<pre>SelectedFile := FileSelect(3, , "Open a file", "Text Documents (*.txt; *.doc)")
if SelectedFile = ""
    MsgBox "The user didn't select anything."
else
    MsgBox "The user selected the following:`n" SelectedFile</pre>
</div>

<div class="ex" id="ExMulti">
<p><a href="#ExMulti">#2</a>: Multi-select example.</p>
<pre>files := FileSelect("M3")  <em>; M3 = Multiselect existing files.</em>
if files = ""
{
    MsgBox "The user pressed cancel."
    return
}
Loop parse, files, "`n"
{
    if A_Index = 1
        MsgBox "The selected files are all contained in " A_LoopField
    else
    {
        Result := MsgBox("The next file is " A_LoopField ". Continue?",, 4)
        if Result = "No"
            break
    }
}
return</pre>
</div>

</body>
</html>